home *** CD-ROM | disk | FTP | other *** search
/ X User Tools / X User Tools (O'Reilly and Associates)(1994).ISO / sun4c / archive / tcltk.z / tcltk / man / cat3 / Async.3 < prev    next >
Text File  |  1994-09-20  |  8KB  |  199 lines
  1.  
  2.  
  3.  
  4. Tcl_AsyncCreate(3)   Tcl Library Procedures                   7.0
  5.  
  6.  
  7.  
  8. _________________________________________________________________
  9.  
  10. NAME
  11.      Tcl_AsyncCreate,       Tcl_AsyncMark,       Tcl_AsyncInvoke,
  12.      Tcl_AsyncDelete - handle asynchronous events
  13.  
  14. SYNOPSIS
  15.      #include <tcl.h>
  16.  
  17.      extern int tcl_AsyncReady;
  18.  
  19.      Tcl_AsyncHandler
  20.      Tcl_AsyncCreate(_p_r_o_c, _c_l_i_e_n_t_D_a_t_a)
  21.  
  22.      Tcl_AsyncMark(_a_s_y_n_c)
  23.  
  24.      int
  25.      Tcl_AsyncInvoke(_i_n_t_e_r_p, _c_o_d_e)
  26.  
  27.      Tcl_AsyncDelete(_a_s_y_n_c)
  28.  
  29. ARGUMENTS
  30.      Tcl_AsyncProc      *_p_r_o_c        (in)      Procedure       to
  31.                                                invoke  to  handle
  32.                                                an    asynchronous
  33.                                                event.
  34.  
  35.      ClientData         _c_l_i_e_n_t_D_a_t_a   (in)      One-word value  to
  36.                                                pass to _p_r_o_c.
  37.  
  38.      Tcl_AsyncHandler   _a_s_y_n_c        (in)      Token  for   asyn-
  39.                                                chronous     event
  40.                                                handler.
  41.  
  42.      Tcl_Interp         *_i_n_t_e_r_p      (in)      Tcl interpreter in
  43.                                                which  command was
  44.                                                being    evaluated
  45.                                                when  handler  was
  46.                                                invoked,  or  NULL
  47.                                                if   handler   was
  48.                                                invoked when there
  49.                                                was no interpreter
  50.                                                active.
  51.  
  52.      int                _c_o_d_e         (in)      Completion    code
  53.                                                from  command that
  54.                                                just completed  in
  55.                                                _i_n_t_e_r_p,  or  0  if
  56.                                                _i_n_t_e_r_p is NULL.
  57. _________________________________________________________________
  58.  
  59.  
  60.  
  61.  
  62.  
  63. Tcl                                                             1
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70. Tcl_AsyncCreate(3)   Tcl Library Procedures                   7.0
  71.  
  72.  
  73.  
  74. DESCRIPTION
  75.      These procedures provide a safe mechanism for  dealing  with
  76.      asynchronous  events such as signals.  If an event such as a
  77.      signal occurs while a Tcl script is being evaluated then  it
  78.      isn't  safe  to  take  any substantive action to process the
  79.      event.  For example, it isn't safe to evaluate a Tcl  script
  80.      since  the  intepreter  may  already  be  in  the  middle of
  81.      evaluating a script; it may not even  be  safe  to  allocate
  82.      memory,  since  a  memory allocation could have been in pro-
  83.      gress when the event occurred.  The only safe approach is to
  84.      set  a  flag indicating that the event occurred, then handle
  85.      the event later when the  world  has  returned  to  a  clean
  86.      state, such as after the current Tcl command completes.
  87.  
  88.      Tcl_AsyncCreate creates an asynchronous handler and  returns
  89.      a  token  for  it.  The asynchronous handler must be created
  90.      before any occurrences of the asynchronous event that it  is
  91.      intended  to  handle  (it is not safe to create a handler at
  92.      the time of an event).  When an  asynchronous  event  occurs
  93.      the  code  that detects the event (such as a signal handler)
  94.      should call Tcl_AsyncMark with the token  for  the  handler.
  95.      Tcl_AsyncMark will mark the handler as ready to execute, but
  96.      it will not invoke the handler immediately.  Tcl  will  call
  97.      the  _p_r_o_c  associated with the handler later, when the world
  98.      is in a safe state, and _p_r_o_c can then carry out the  actions
  99.      associated  with  the  asynchronous event.  _P_r_o_c should have
  100.      arguments and result that match the type Tcl_AsyncProc:
  101.           typedef int Tcl_AsyncProc(
  102.                ClientData _c_l_i_e_n_t_D_a_t_a,
  103.                Tcl_Interp *_i_n_t_e_r_p,
  104.                int _c_o_d_e);
  105.      The _c_l_i_e_n_t_D_a_t_a will be the same as the  _c_l_i_e_n_t_D_a_t_a  argument
  106.      passed  to Tcl_AsyncCreate when the handler was created.  If
  107.      _p_r_o_c is invoked just after a command has completed execution
  108.      in an interpreter, then _i_n_t_e_r_p will identify the interpreter
  109.      in which the command was evaluated and _c_o_d_e will be the com-
  110.      pletion code returned by that command.  The command's result
  111.      will be present in _i_n_t_e_r_p->_r_e_s_u_l_t.  When _p_r_o_c returns, what-
  112.      ever  it  leaves  in  _i_n_t_e_r_p->_r_e_s_u_l_t will be returned as the
  113.      result of the command and the integer value returned by _p_r_o_c
  114.      will be used as the new completion code for the command.
  115.  
  116.      It is also possible for _p_r_o_c to be invoked  when  no  inter-
  117.      preter is active.  This can happen, for example, if an asyn-
  118.      chronous event occurs while the application is  waiting  for
  119.      interactive  input  or an X event.  In this case _i_n_t_e_r_p will
  120.      be NULL and _c_o_d_e will be 0, and the return value  from  _p_r_o_c
  121.      will be ignored.
  122.  
  123.      The procedure Tcl_AsyncInvoke is called to invoke all of the
  124.      handlers that are ready.  The global variable tcl_AsyncReady
  125.      will be non-zero  whenever  any  asynchronous  handlers  are
  126.  
  127.  
  128.  
  129. Tcl                                                             2
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136. Tcl_AsyncCreate(3)   Tcl Library Procedures                   7.0
  137.  
  138.  
  139.  
  140.      ready;   it can be checked to avoid calls to Tcl_AsyncInvoke
  141.      when there are no ready handlers.  Tcl checks tcl_AsyncReady
  142.      after each command is evaluated and calls Tcl_AsyncInvoke if
  143.      needed.   Applications  may  also  call  Tcl_AsyncInvoke  at
  144.      interesting  times  for that application.  For example, Tk's
  145.      event handler checks tcl_AsyncReady  after  each  event  and
  146.      calls  Tcl_AsyncInvoke if needed.  The _i_n_t_e_r_p and _c_o_d_e argu-
  147.      ments to Tcl_AsyncInvoke have the same meaning as for  _p_r_o_c:
  148.      they identify the active intepreter, if any, and the comple-
  149.      tion code from the command that just completed.
  150.  
  151.      Tcl_AsyncDelete removes an asynchronous handler so that  its
  152.      _p_r_o_c  will never be invoked again.  A handler can be deleted
  153.      even when ready, and it will still not be invoked.
  154.  
  155.      If multiple handlers become active at  the  same  time,  the
  156.      handlers  are invoked in the order they were created (oldest
  157.      handler first).   The  _c_o_d_e  and  _i_n_t_e_r_p->_r_e_s_u_l_t  for  later
  158.      handlers reflect the values returned by earlier handlers, so
  159.      that the most recently created handler has  last  say  about
  160.      the  interpreter's  result  and  completion  code.   If  new
  161.      handlers  become  ready  while   handlers   are   executing,
  162.      Tcl_AsyncInvoke  will  invoke  them  all;   at each point it
  163.      invokes the highest-priority (oldest) ready handler, repeat-
  164.      ing  this  over and over until there are no longer any ready
  165.      handlers.
  166.  
  167.  
  168. WARNING
  169.      It is almost always a bad idea  for  an  asynchronous  event
  170.      handler  to modify _i_n_t_e_r_p->_r_e_s_u_l_t or return a code different
  171.      from its _c_o_d_e argument.  This sort of behavior  can  disrupt
  172.      the  execution  of scripts in subtle ways and result in bugs
  173.      that are extremely difficult to track down.  If an asynchro-
  174.      nous  event  handler  needs  to evaluate Tcl scripts then it
  175.      should first save _i_n_t_e_r_p->_r_e_s_u_l_t  plus  the  values  of  the
  176.      variables  errorInfo  and  errorCode  (this can be done, for
  177.      example, by storing them  in  dynamic  strings).   When  the
  178.      asynchronous  handler  is finished it should restore _i_n_t_e_r_p-
  179.      >_r_e_s_u_l_t, errorInfo, and errorCode, and return the _c_o_d_e argu-
  180.      ment.
  181.  
  182.  
  183. KEYWORDS
  184.      asynchronous event, handler, signal
  185.  
  186.  
  187.  
  188.  
  189.  
  190.  
  191.  
  192.  
  193.  
  194.  
  195. Tcl                                                             3
  196.  
  197.  
  198.  
  199.